Bug Proofing Visual Basic: A Guide to Error Handling and Prevention
(Publisher: John Wiley & Sons, Inc.)
Author(s): Rod Stephens
ISBN: 0471323519
Publication Date: 11/01/98

If all of the actions are long, place a comment next to the Else clause to remind the reader of the condition. In fact, it never hurts to put this kind of comment next to all Else statements even if the amount of code is small.

If condition Then
        :
    ‘ Many lines of code.
        :
Else     ‘ Not condition.
        :
    ‘ Many lines of code.
        :
End If

The same techniques apply to Select statements.

    Case value1
        ‘ Do something brief.
    Case value2
        ‘ More code.
            :
    Case value2
            :
        ‘ Many lines of code.
            :
End Select

Avoid Wizards

Code wizards are designed to simplify programming by automatically generating code to perform common tasks. Unfortunately, they often generate code that is practically unreadable by humans. If there is a problem with the code, it is usually difficult to find and fix. If you later need to use the wizard to regenerate the code, perhaps to specify new parameters, any changes you have made to the code are lost.

Many wizards are all-or-nothing propositions. You should either leave the automatically generated code completely unchanged, or you should use the code only as a starting point for your own code.

If you leave the code unchanged, you can use the wizard to regenerate it later. Since you have made no modifications to the code, you cannot lose any changes you have made. The only change you should consider making is the addition of large comments saying that the code is automatically generated and warning not to edit it.

‘ *******************************************************
‘WARNING: This code was automatically generated by the
‘         TableReader wizard. Do not modify it manually.
‘         If you do, your changes will be lost the next
‘         time the wizard runs.
‘*******************************************************

Alternatively, you can use the wizard to generate a starting point for your own code. After the wizard creates the code, you modify and maintain the code manually and never regenerate it using the wizard. Any changes to the code are your sole responsibility.

While the code initially generated by the wizard may be hard to read, you do not need to rewrite it immediately. If the code works, do not break it by trying to make it easier to read. Instead, wait until you must rewrite the code and then do it properly.

Use Meaningful Names

Give variables and routines meaningful names instead of short abbreviations. There is no advantage to naming a variable EOTW instead of EmployeeOfTheWeek. This only makes the code less obvious and makes the reader focus on memorizing abbreviations instead of learning the program’s structure.

You can reasonably use abbreviations that are standard in your industry. For example, in telephone companies the abbreviation POTS stands for “Plain Old Telephone Service” and means basic residential service. A telephone company service system could reasonably include a variable named HasPots because POTS is a well-known telephone company abbreviation.

Most readers will also be able to understand abbreviations that follow a pattern. For example, a group of abbreviations that use the prefix Num to mean Number is reasonably easy to understand.

NumEmployees As Integer
NumCompanies As Integer
NumOrders As Integer
    :

Standardize Abbreviations

Standardize any abbreviations you do use. Discuss them with the other developers on the project and develop consistent rules of use. For example, you might decide that Number will be abbreviated Num. If different developers use Num, NumberOf, Number, No, and Count all to mean Number, the code will be confusing.

NumEmployees As Integer
NumberOfCompanies As Integer
NoOrders As Integer
NBills As Integer
ItemCount As Integer
    :

Use Similar Names for Similar Purposes

Use similar names for similar variables and routines. When a reader learns the meaning of one name, its similarity to other names can help him learn their meanings, too. Suppose the program has routines named PrintEmployeeReport, PrintJobReport, and PrintInventoryReport. The reader will quickly learn that report-printing routines are named PrintXxxReport. He will expect the subroutine that prints tax reports to be named PrintTaxReport. If you name that routine ReportOnTaxes, the reader may become confused.

At the same time, do not use similar variable and routine names for dissimilar purposes. For example, suppose the RemoveCompany subroutine deletes a company record from a database. In that case, the RemoveEmployee subroutine should delete an employee record from the database. It should not merely set the employee’s work status to Vacation, leaving the record in the Employees table. Giving these two routines such similar names will mislead the reader into thinking they have similar purposes.

Don’t Reuse Variables

If you need a variable for a new purpose, create a new variable instead of reusing an old one. Using the same variable i to loop through two arrays is fine because i is used as a looping variable in both places. Using i as a looping variable in one place and as a file number in another will be very confusing.

    ‘ Search for a specific job number.
    For i = LBound(jobs) To UBound(jobs)
        If jobs(i) = target_job Then Exit For
    Next i
        :
    ‘ Open a file.
    i = FreeFile
        :
    Open “C:\Data\jobs.dat” For Append As i

The problem with this code is that someone modifying the code later may forget what the variable is for and when it is in use for which purpose. If you forget that i is the open file number and you change the code so i is modified while the file is open, you will introduce a bug.

    ‘ Find the smallest job number.
    min_job = jobs(LBound(jobs))
    For i = LBound(jobs) + 1 To UBound(jobs)
        If min_job > jobs(i) Then min_job = jobs(i)
    Next i

    ‘ Save the smallest job number.
    Print #i, min_number

Make the code obvious by creating separate variables for separate purposes.

Use Next i

Use the looping variable’s name in Next statements. For example, use the first style shown in the following code.

‘ Use this style:
For i = 1 To 100
    :
Next i

‘ Do not use this version:
For i = 1 To 100
    :
Next

This makes the code more obvious. If you are reading the code for a long For loop and you come to the Next statement, using the looping variable’s name makes it obvious which loop is ending.

You can make understanding the loop even easier by using a meaningful name for the looping variable. Using the name employee_index instead of i tells the code’s reader that the loop manipulates employees in some way. You can make the loop’s purpose completely clear with two comments, one before and one after the loop.

‘ Print the employees.
For employee_index = 1 To 100
    :
Next employee_index    ‘ Print the next employee.